SDA 4.1 Documentation for LISTCASE

NAME

listcase - List values of individual cases

USAGE

listcase -b batch_filename
OR
listcase -options (for command-line version)

DESCRIPTION

LISTCASE is a program to produce a case-by-case listing of the values of a specified set of variables. One or more filter variables can be used, in order to limit the listing to a subset of the cases in the dataset.

All selected cases are listed, including those with missing-data codes. However, the missing-data codes are not included in the calculation of summary statistics, if statistics are requested.

CONTENTS OF THIS DOCUMENT

Calculation and Display of Percentages
Modes of Execution
- Batch File Execution (-b)
  - Keywords for Batch File Execution
  - Examples of Batch Files
- Command-Line Execution (without -b)
  - Option Flags for Command-Line Execution
  - Examples of Command-Line Specifications

CALCULATION AND DISPLAY OF PERCENTAGES

In addition to (or instead of) displaying the values of variables, it is possible to calculate and display the percent of one variable divided by another variable. (Both variables must be numeric variables.) This is particularly useful when some of the variables in the data file represent aggregate units such as cities.

To calculate and display a percent, use the following formats, beginning with $p, when specifying the variables to be listed:

$p(var1, var2): This will display the value: 100 * var1 / var2
(using 1 decimal place) where 'var1' and 'var2' are variables in the dataset. It is not necessary that either 'var1' or 'var2' be specified separately for listing.
$p(var1, var2, 2): To display a percent using other than one decimal place, specify the desired number of decimal places after var2. The example above would use 2 decimal places.
$p(demo, totvote, "Percent democratic"): To give your own name to the percentage created, put the name you want within double quotes. This name will be displayed at the top of the column for that percentage.

Note that this percentaging capability is not available in command-line mode.

MODES OF EXECUTION

The program runs in three modes.

Interactive Mode
When the SDA Web interface runs the program, users do not have to deal with the keywords or the command-line flags given in this document. Instead, the options are selected right on the screen, and the HTML output from the program goes directly to the user's Web browser.
Batch Mode
To run the program in batch mode it is necessary to prepare a command file, which specifies the variables to be listed and the options to use. This document explains how to prepare such a file. The name of this batch command file is specified to the program after the '-b' option flag. See the batch file keywords below.
The output from the program is an HTML file, in the same format as produced when the program is run interactively.
Command-Line mode
To run the program in command-line mode (using options other than '-b'), the specifications are given by using the various option flags described below. In command-line mode, the output from the program is generated in plain text (not HTML) and is sent to the standard output (which is the user's screen by default). The output can be redirected to a file in the usual way by using '>'. The plain text output includes only the variable values, one case on each line. There are no column headings.
The command-line version of the program is intended to be used primarily for diagnostic purposes. It cannot generate percentages or statistics, force variable names to upper or lower case, or limit the output to some maximum number of cases. However, it does allow for filter variables, and it can display category labels in addition to the code values. See below for an explanation of the available command-line options.

BATCH FILE EXECUTION

Keywords for Batch File Execution

The name of the batch file is given after '-b' on the command line. It contains the specifications for the listing. These specifications are given in the form "keyword = something" with one keyword per line. Keywords may be given in any order, either in upper or in lower case. The valid keywords are as follows (with significant characters shown in capital letters):


Keyword       Possible Specification          Default (if no keyword)
_____________________________________________________________________


STUdy=        path of dataset directory       Look for variables only in
                                                current directory

VARiables=    variable name(s)                REQUIRED
               (separated by spaces/commas)
               can specify percents, as well
               as individual variables

Filter=       name(s) and codes of filter     No filter
                variable(s)

GVARCase=     LOWER or UPPER                  No force to lower/upper case

SAvefile=     filename to receive output      Output (HTML) sent to screen
                (overwrite existing file)       (the standard output)

VALues=       (how to display numeric vars)
               Codes - numeric codes          Both
               Labels - category labels
                (if any; otherwise codes)
               Both - Codes AND labels

MAXCases=     max number of cases to display  500

STATistics=   mean, sum, min, max             No summary statistics

COLOR=        Yes                             No color for heading

LAnguagefile= Name of file with non-English   English labels on
                labels and messages             output

RUNtitle=     Title or comment for this run   No title or comment
                of the program

TExt=         Yes                             No text for variables

Abbreviations

Keywords can be abbreviated down to the number of characters required to differentiate them from other keywords. Usually only a few characters are required. The keyword for the list of variables, for instance, can be given as "variables=" or "vars=". Either upper or lower case may be used.

Repetition of Keywords

If there is not enough room on a line to list all of the desired variables, the keyword can be repeated on a new line, and more variables can be listed. In such a case the second list is appended to the first list, for purposes of generating tables. This appending feature only applies to the keywords for specifying the variables to be listed and the filter variables. If other keywords are repeated, the program will print an error message and stop.

Comments

Anything on a line beginning with "#" is ignored by the batch processor and can therefore be used for comments. Blank lines are also ignored.

Examples of Batch Files


# Basic example

     vars = spend spend2 spend3
     filter = age(18-20) gender(1)

     savefile = mylist.htm

---------------------------------------------

# Specify that only category labels be output
# (If a category has no label, the numeric
#  code value will be output.)
# Also restrict the output to a specified age and gender group.

     vars = spend spend2 spend3
     filter = age(18-20) gender(1)

     values = labels

     savefile = mylist.htm

---------------------------------------------

# Get percentages as well as individual variables
# For example, the percent of total income
#  represented by wages

     vars = wages, totincom, $p(wages,totincom)

     filter = age(18-20) gender(1)
     savefile = mylist.htm

---------------------------------------------

# Specify the location of the SDA study dataset.
# Also specify a run title and request the output of question text
#    for the specified variables.

     study = /sa/sdatest
     vars = spend spend2 spend3 spend4
     filters= age(18-50) party(1-3)

     runtitle = List the values of the spending variables
     text = yes

     savefile= mylist.htm

COMMAND-LINE EXECUTION

Option Flags for Command-Line Execution

The LISTCASE program is executed in command-line mode whenever option flags other than `-b' are used. The meaning of the available options is as follows:

-a

List only the CASEID values.

-f filter(s)

Filter specifications to limit the cases to be displayed.
An example of a filter specification is: -f "age(18-25),gender(2)"
Note that double quotes are ALWAYS necessary around the filter specifications. (On Linux, single quotes might also work, but double quotes are definitely required for Windows.)

-v varlist

List of variables for which the code values will be displayed. Names of variables can be separated by commas or blanks. If they are separated by blanks, the whole list of variables needs to be put in double quotes.

A variable name may be given with a range restriction like "age(18-20)". This has the same effect as a filter specification. If a range restriction is used, that variable specification must be put in double quotes (unless the whole list of variables is already in quotes).

If you want to display a CASEID variable, you must specify that variable name in the list of requested variables. That variable is no longer displayed automatically by LISTCASE.

-s path

Look for variables in the specified study path(s) in addition to the current directory.

-l

Show the category label, in addition to the category value, for each case listed.
(This option flag is a lower-case 'L'.)

-h

Display (only) a list of options. The list of options is also displayed if no option flags at all are included on the command line.

EXAMPLES OF COMMAND-LINE SPECFICATIONS

listcase -v CASEID -f "age(18-25)": List CASEID values for cases with the values 18-25 on age.
listcase -v age,educ,gender -f "region(1)": List values of age, educ, and gender for cases in region 1.
listcase -l -v "income(1-5)": List category values and labels on the income variable for everyone with response categories 1-5 on that variable.
listcase -l -v "income(1-5)" | more: Same as previous example, but display output one page at a time
listcase -l -v "income(1-5)" > mylisting.txt: Same as previous example, but redirect output to a file (instead of to the user's screen).

CSM, UC Berkeley/ISA
September 17, 2019